home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Misc Servers / Zope.exe / HELPSYS.TXT < prev    next >
Encoding:
Text File  |  2000-02-15  |  4.7 KB  |  126 lines
  1. Zope Help System
  2.  
  3.   The Zope Help System provides context-sensitive on-line help for
  4.   Zope users. The system is flexible and can provide help for
  5.   Python and ZClass-based Zope Products.
  6.   
  7.   In the future the Help System will be expanded to provide additional
  8.   help including API documentation.
  9.   
  10. Using the Help System
  11.  
  12.   Every standard Zope management screen should include a help button
  13.   which provides access to help for that screen.
  14.  
  15.   Additionally all the installed help topics can be browsed and
  16.   searched.
  17.   
  18. Architecture
  19.  
  20.   The Help System is based around Zope Products. When a product is
  21.   installed, its help objects are installed along with it. All help
  22.   content is associated with a product.
  23.   
  24.   Help content is provided by 'Help Topic' objects. These objects live
  25.   inside Product folders within a special container object called a
  26.   'Product Help' object. When you browse a Product folder in the
  27.   Control Panel you will see these 'Product Help' objects and their
  28.   'Help Topics'.
  29.  
  30.   In general you get access to the Help System through the help system
  31.   object which has methods for drawing help buttons. This object lives
  32.   in the Zope application object and has an id of 'HelpSys'.
  33.   
  34. Writing Help for ZClasses
  35.  
  36.   Suppose you've created an addable type of object with ZClasses.
  37.   You'd like the management screens of your objects to have help
  38.   buttons just like the standard Zope management screens.
  39.   
  40.   First create some Help Topics though the web which document your
  41.   management screens. Do this by going to your ZClass's Product and
  42.   creating new Help Topics inside the Product Help object.
  43.   
  44.   Next go to your ZClass and click on the 'Views' management tab. On
  45.   this screen you define your object's management views. Each view has
  46.   a name, a method, and optionally a help topic. If you select a help
  47.   topic for a view, a help button will be drawn on that management
  48.   view and it will be linked to the help topic you select.
  49.   
  50. Writing Help for Python Products
  51.  
  52.   To support help your Python product needs to register help topics
  53.   during product registration, and it needs to indicate which help
  54.   topics should be associated with which management screens.
  55.   
  56.   Registering Help Topics
  57.  
  58.     To register help topics use the 'registerHelp' method on the
  59.     ProductContext object. For example::
  60.  
  61.       def initialize(context):
  62.         ...
  63.         context.registerHelp()
  64.  
  65.     This method will create help topics for all files found in the
  66.     'help' subdirectory of the product. Supported file types include:
  67.     .html, .htm, .txt, .stx, .dtml, .gif, .jpg, .png. Appropriate
  68.     classes of help topics are used depending on the suffix of the
  69.     help files.
  70.  
  71.     If you want more control over how your help topics are created you
  72.     can use the 'registerHelpTopic' method that takes an id and a help
  73.     topic object as arguments. For example::
  74.  
  75.       from mySpecialHelpTopics import MyTopic
  76.  
  77.       def initialize(context):
  78.         ...
  79.         context.registerHelpTopic('myTopic', MyTopic())
  80.   
  81.   Associating Help Topics with Management Screens      
  82.     
  83.     The chief way to bind a help topic to a management screen is to
  84.     include information about the help topic in the class's
  85.     'manage_options' structure. For example::
  86.     
  87.       manage_options=(
  88.         {'label':'Edit', 
  89.          'action':'editMethod',
  90.          'help':('productId','topicId')},
  91.         )
  92.  
  93.     In this example, 'productId' refers to the name of the Zope
  94.     Product in which the class is defined, and 'topicId' refers to the
  95.     id of the Help Topic associated with this management view.
  96.     
  97.     When Zope draws the management view it will automatically include
  98.     a help button pointing to the right help topic if you provide this
  99.     information in the 'manage_options' structure. 
  100.     
  101.     Note: sometimes Zope gets confused and defaults to highlighting
  102.     the first management tab in place of the correct one. To fix this,
  103.     set the 'management_view' variable to the name of the correct
  104.     view. If the wrong view is hilighted, then the wrong help button
  105.     will be drawn.
  106.  
  107.     To draw a help button on a management screen that is not a view,
  108.     use the 'HelpButton' method of the 'HelpSys' object like so::
  109.     
  110.       <dtml-var "HelpSys.HelpButton('productId', 'topicId')">
  111.       
  112.     This will draw a help button linked to the specified help topic.
  113.     If you prefer to draw your own help button you can use the helpURL
  114.     method instead like so::
  115.  
  116.       <dtml-var "HelpSys.helpURL(
  117.         topic='productId',
  118.         product='topicId')">
  119.       
  120.     This will give you a URL to the help topic. You can choose to draw
  121.     whatever sort of button or link you wish.
  122.     
  123.     
  124.       
  125.       
  126.